Skip to content

Add exact writer epoch opens - #9

Merged
xav-db merged 15 commits into
mainfrom
codex/exact-writer-epoch
Aug 31, 2026
Merged

xav-db merged 15 commits into
mainfrom
codex/exact-writer-epoch

Conversation

@xav-db

@xav-db xav-db commented Aug 21, 2026 •

Copy link
Copy Markdown
Member

Summary

  • let managed callers open a writer at an exact nonzero authority epoch
  • reject lower and equal stale epochs through the manifest fencing boundary
  • preserve last-writer-open behavior for unmanaged callers
  • integrate exact epochs with the current 0.15 WAL writer initialization path
  • cover exact claims and existing fencer behavior

Stack

Required by HelixDB slatedb#1018 and Hyperscale slatedb#260.

The dependency revision is c64286e.

@xav-db

xav-db commented Aug 21, 2026

Copy link
Copy Markdown
Member Author

Validation update:

  • Full locked all-feature SlateDB tests pass: 2,091 unit tests plus integration and doc-test suites (with only declared ignored tests).
  • Required workspace Clippy with warnings denied and formatting checks pass.
  • The Node binding build and 49/49 tests pass locally.
  • The original hosted Node job became stuck inside node --test despite the local suite completing in under two seconds. I cancelled that anomalous run and reran only the cancelled dependency path; the hosted Node job then passed in 4m46s, including package-content checks.
  • All PR checks are now green.

@xav-db
xav-db force-pushed the codex/exact-writer-epoch branch from c64286e to 7e23044 Compare August 31, 2026 10:31
@xav-db
xav-db marked this pull request as ready for review August 31, 2026 11:35
@xav-db
xav-db merged commit d352545 into main Aug 31, 2026
2 of 5 checks passed
xav-db added a commit to HelixDB/helix-db that referenced this pull request Aug 31, 2026
## Summary

- open every managed writer with the caller supplied nonzero authority
epoch
- rely on native SlateDB epoch fencing for lower-term, equal-term,
concurrent, and delayed stale opens
- add a request-local commit gate for bounded drain classification
without durable receipts or replay
- expose terminal retry classification across the Rust, TypeScript,
Python, and Go SDKs

## Stack

- SlateDB exact-epoch dependency:
HelixDB/slatedb#9
- pinned SlateDB commit: c64286ec8e5aaa724f12a8c54b58fe73efcff534
- consumed by Hyperscale:
HelixDB/helix-hyperscale#260

## Safety

- only a verified pre-execution rejection can return request ownership
- commit-start and drain-abort claims are mutually exclusive
- unknown write outcomes are terminal and never automatically retried
- authority exhaustion at u64::MAX remains intentionally unsupported

## Validation

Locked all-target/all-feature workspace compile passes on SlateDB 0.15.
Managed-writer lower/equal, concurrent, delayed stale, and in-flight
fencing tests pass. The locked migration parity dev suite passes
end-to-end. Fresh CI is rerunning after the final Python contract
formatting fix; full tests, Clippy, docs, SDK, and linked nine-node
validation remain in progress.

<!-- greptile_comment -->

<h3>Greptile Summary</h3>

The PR introduces exact-epoch managed-writer fencing, typed
reader-retirement cancellation, and terminal classification for unknown
commit outcomes. It also aligns the transport and SDK error contracts
and expands fencing, lifecycle, migration, and scale coverage.

- Managed writer opens pass a nonzero caller-supplied authority epoch to
SlateDB while embedded writer behavior remains separate.
- Reader retirement cooperatively cancels admitted reads with a
dedicated stable error code.
- HTTP reports unknown commit outcomes as unavailable with an explicit
non-retryable marker; gRPC reports them as unavailable with stable
metadata.
- Rust, TypeScript, Python, and Go SDKs expose explicit retry
classification without inferring retryability from status alone.
- CI and production contract coverage gain dedicated vector-migration
scale and writer-fencing checks.

<details><summary><h3>Important Files Changed</h3></summary>




| Filename | Overview |
|----------|----------|
| crates/db/src/lib.rs | Adds the managed-writer open mode, propagates
exact authority epochs to SlateDB, and exercises stale, equal,
concurrent, and in-flight fencing behavior. |
| crates/db/src/execution_control.rs | Adds monotonic reader-retirement
cancellation and integrates it with deadline-aware cooperative
execution. |
| crates/db/src/error.rs | Introduces typed retirement cancellation and
classifies fenced commit outcomes as terminal rather than transaction
conflicts. |
| crates/db/src/query_service.rs | Exposes predicates that let
transports distinguish reader retirement, deadlines, conflicts, and
unknown commit outcomes. |
| crates/server/src/http.rs | Maps unknown commit outcomes to HTTP 503
and emits an explicit `retryable: false` field. |
| crates/server/src/grpc.rs | Maps unknown commit outcomes to gRPC
Unavailable while retaining the stable error code in metadata. |
| sdks/rust/src/lib.rs | Preserves explicit retry metadata on remote
errors and retries only when the server supplies Boolean true. |
| sdks/typescript/src/index.ts | Adds optional retry metadata and
fail-closed retry classification to the TypeScript error contract. |
| sdks/python/src/helixdb/_client_common.py | Parses explicit retry
metadata in both current and legacy envelopes and exposes fail-closed
retry classification. |
| sdks/go/client.go | Adds optional retry metadata to remote errors and
requires explicit true for retryable classification. |

</details>


<details><summary><h3>Sequence Diagram</h3></summary>

```mermaid
sequenceDiagram
    participant C as Managed caller
    participant H as HelixDB
    participant S as SlateDB
    participant T as Transport
    participant SDK as Client SDK
    C->>H: Open writer with nonzero authority epoch
    H->>S: Open using exact writer epoch
    S-->>H: Writer opened or fenced
    C->>H: Execute write
    H->>S: Commit transaction
    alt commit succeeds
        S-->>H: Committed
        H-->>T: Success
    else fencing makes outcome unknown
        S-->>H: Fenced commit result
        H-->>T: Unknown outcome
        T-->>SDK: "503 / unavailable, retryable=false"
        SDK-->>C: Terminal error
    end
```
</details>

<sub>Reviews (1): Last reviewed commit: ["Accept disjoint membership
storage in
re..."](85e6a97)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=58590933)</sub>

<details><summary><h4>Context used (4)</h4></summary>

- Knowledge Base — [Database
engine](https://app.greptile.com/helixdb/-/custom-context/knowledge-base/helixdb/helix-db/-/docs/database-engine.md)
- Knowledge Base — [Interpreter
execution](https://app.greptile.com/helixdb/-/custom-context/knowledge-base/helixdb/helix-db/-/docs/interpreter-execution.md)
- Knowledge Base — [Client SDKs and
bindings](https://app.greptile.com/helixdb/-/custom-context/knowledge-base/helixdb/helix-db/-/docs/client-sdks-and-bindings.md)
- Knowledge Base — [Server and
transports](https://app.greptile.com/helixdb/-/custom-context/knowledge-base/helixdb/helix-db/-/docs/server-and-transports.md)
</details>


<!-- /greptile_comment -->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant